Ever wrote a technical documentation and wondered why users are busy filling up the StackOverflow website with high ranked questions about your tool or framework over and over again?
Perhaps, from all those many questions, you are getting impressed by the popularity of your tool or framework due to these many public questions.
Or you may be asking yourself: Why are these people still asking all those silly questions? We put
so much effort into answering all those questions in our precious documentation, right at the ready.
Why don't they just read it? It's all there!
You may have put months of valuable effort into writing your documentation – and your users just don't seem to read it. … Or don't they just get what you wrote?
Perhaps your documentation isn't giving them the answers they are looking for when they are searching for answers.
Well, you've come to the right place now. It's time to improve you documentation. Let's start right now!
10 Simple Tips To Create An Outstanding Technical Documentation
Target your audience
Usually, almost all of your users are willing and keen to use your tool or framework to accomplish their own projects. Only a tiny remaining fraction of users is seriously considering to contribute to your tool or framework. Don't address them both in the same documentation.
Users, plug-in authors and contributors have different, diverging demands:
Users just want to be able to apply your tool or framework to their project fast. Keep them away from reading though internal technical details or extensibility options for your tool or framework.
Plug-in authors and contributors, however, need to know the technical details and extensibility options of your tool or framework. They already know every detail about how your tool or framework is to be applied. So, refrain from providing basic usage information to this audience.
Create separate pieces of documentation for users and contributors
Be structured
When studying one of your documentation's pages, users expect to find all information regarding one single topic on that page. They don't expect to find other, unrelated information.
Your readers urge to get the full picture and acquire a dedicated, narrow piece information fast. They want to quickly get your tool or framework working the way they need. So, keep focussed!
Don't be a butterfly, prancing from flower to flower, giving hints or how-tos on unrelated or loosely coupled information you believe may be useful to know. Your users won't be able to rediscover these unrelated pieces of information later again.
Keep focussed. Don't intermingle hints or how-tos in our documentation.
Don't repeat yourself
When you have been reading another project's documentation in order to get a complex task done, you may have found yourself reading quite a number of pages, all containing the same set of warnings, hints and intruductory text.
This is particularly annoying when these injected pieces of information tend to fill the majority of each page. A reader cannot tell unimportant from important pieces of information before that piece of information has been read. So, providing warnings and information boxes over and over again becomes an annoying waste of time for the reader.
Dedicate a separate page to your documentation containing all warnings and intruductory text at one single place. Refer to this page with a hyperlink from all the other pages that need these warnings and information boxes applied.
Don't repeat warnings and intruductory text across pages of your documentation.
Look through your reader's eyes
Don't invite users to examine your tool's source code in order to understand how it works.
Your readers are not willing to become members of your team. And they shouldn't be supposed to. Your readers are getting paid for working with their own team, trying to get their own projects accomplished. Your tool or framework is not the focal point of their daily work. It's just one of many tools your readers are working with.
So, always briefly explain the implications of setting a property or option: What will change? What is the default value? What is the allowed range of values? What data type is it? Which areas of your tool or framework will be affected? What errors may occur? Why?
Write your documentation in a way readers may safely consider your code being a black box, not to be looked at, not to be considered at all. The ramifications of your tool or framework to their project should be the only important focus in your documentation.
Take the perspective of your reader.
Separate how-tos, guides and reference documentation
Reading into a tool or framework for the first time, it makes sense to get acquainted with the most common usage scenarios and code samples first, then learning about some more advanced techniques.
When your tool or framework finally becomes getting used, reference documentation becomes more and more important for quickly finding information on a very focussed topic.
So, create separate documentation books for each phase of the reader's knowledge:
Write a Programming Guide book to introduce common usage patterns to your novice readers. Explain what they can do using dedicated parts of your tool or framework. Be precise. Give simple sample use cases. Refrain from advertising your tool or framework. Your readers already chose your product. They wouldn't have taken the precious effort of reading through your documentation otherwise.
Next, write a separate How-to book, giving vivid examples for dedicated parts of your tool or framework. This will help readers who don't want to create their own code, so they can simply copy and past existing solution snippets.
In your How-to book, don't forget to link to corresponding parts of your Programming Guide.
Finally, write a Reference book, explaining each interface, class, property, method or configuration in detail. Don't expect your readers to jump and read any other part of your documentation, except for other reference material. Be exhaustive, yet stay confined to the topic you're describing.
Provide an intruductory motivation section to each page of the Reference book: Why does this particular interface, class, property, method or configuration setting exist? What will change? What is the default value? What is the allowed range of values? What data type is it? Which areas of your tool or framework will be affected? What errors may occur? Why? — Be very brief, yet exhaustive.
Create separate documentation books, appropriate for each learning phase.
Be educational
When your users read your documentation, you may safely assume they don't have any knowledge about what you're trying to convey.
So, start your pages with a brief motivation section, explaining why the readers should be interested in reading the remainder of the page. What will they learn? What part of your tool or framework is being affected? To what regard?
Then, continue with what you believe are the mostly used properties or parts of this particular detail you want to explain on the page.
If there is some correlation involved: Does the property or setting discussed exclude, contradict or require other settings or properties for your tool or framework to operate properly?
In the course of your page, take your reader on a guided tour through the topic. This is true for Programming Guide, How-to and Reference documentation.
Don't forget to link to correlated reference information at the end of the page.
Guide your readers through a page.
Provide small and simple examples
They say: A picture is worth a thousand words.
To keep your documentation clean and concise, it's often adviced to provide simple examples, explaining how a property or configuration is used in context.
Again, be brief! When you're writing examples, make sure you don't have more than 10 lines of example code unrelated to the interface, class, property, method or configuration setting you try to describe. Your example is not supposed to provide a working application. It's just supposed to briefly demonstrate how to apply the interface, class, property, method or configuration setting in context with other code.
Don't be afraid to use ellipses as a placeholder for other code comes here
if that other code
may be distracting or unnecessarily extending the example, wasting time and space.
Provide examples. Keep them brief.
Support offline reading
Quite a number of users prefer to print their documentation so they will be able to read it when not connected to the Internet.
For many of these users it's more easy to add notes and annotations to a printed page than to a web document. Some users even feel it's easier to memorize information from printed pages because they remember where they read it. Last but not least, it's more sustainable to read a once printed document than to keep servers, switches, routers and hosts online and engaged to keep the same documentation available online.
As you've seen by now, the best way to write documentation for your tool or framework is to provide distinct documentation books per target audience and learning phase (how-tos, guides and reference). Each of these online books should come with an option to get a PDF file created from it. Make sure the style sheets for the printed version will allow for easy reading while minimizing printer, ink and paper wastage.
Provide option to create a PDF document from your documentation.
Be concise
At the image on the right you see a printed version of the Microsoft ASP.NET Core 1.1 documentation. It's 1,200 printed pages worth.
The current volume of the Microsoft ASP.NET 6.0 documentation is flabbergasting 7,000 pages big!
Over the years, this huge pile of information has accumulated and became out of control. Who would be able to maintain this gigantic chunk anyway? It's become a huge pile of text without any educational value, not separating target audience, unrelated information hints or learning stages.
Remember: Your tool or framework is not the centre of the world. Your users' main focus is their own project. Their capacity and resources are naturally confined.
Your users need to split their valuable time and focus between their own project and round about 20 other tools from different providers they are working with for keeping their project up and running and to accomplish their goals. Your tool or framework is just one of these many tools. So, be brief! And precise!
If your tool or framework takes more than 300 pages to explain, you have made huge design flaws and your tool or framework most probably isn't as good as you believe it to be. If you cannot explain your tool or framework concise and clear, your tool or framework is not a time saver – it's rather a waste of time. So, make sure you keep your documentation succinct.
Be concise and precise.
Write in a positive tone
Your readers' task is hard: Benefit from your tool or framework by studying your documentation thoroughly and fast.
Try giving them a good time by choosing your words carefully. Don't be too starchy. Try to write in a positive, supporting tone.
Don't get to casual and distracting. Choose simple words. Remember that your documentation may be read by foreign readers, not too much acquainted with the language you're writing your documentation in.